<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>{include}</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Smarty 3 Manual">
<link rel="up" href="language.builtin.functions.html" title="Chapter 7. Built-in Functions">
<link rel="prev" href="language.function.if.html" title="{if},{elseif},{else}">
<link rel="next" href="language.function.include.php.html" title="{include_php}">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">{include}</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="language.function.if.html">Prev</a> </td>
<th width="60%" align="center">Chapter 7. Built-in Functions</th>
<td width="20%" align="right"> <a accesskey="n" href="language.function.include.php.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="sect1" title="{include}">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="language.function.include"></a>{include}</h2></div></div></div>
<p>
  <code class="varname">{include}</code> tags are used for including other templates in the current
  template. Any variables available in the current template are also
  available within the included template.
  </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>
  The <code class="varname">{include}</code> tag must have
  the  <em class="parameter"><code>file</code></em> attribute
  which contains the template resource path.
  </p></li>
<li class="listitem"><p>
  Setting the optional <em class="parameter"><code>assign</code></em> attribute
   specifies the template variable that the output of
  <code class="varname">{include}</code> is assigned to, instead of being displayed. Similar to
  <a class="link" href="language.function.assign.html" title="{assign}"><code class="varname">{assign}</code></a>.
 </p></li>
<li class="listitem"><p>
  Variables can be passed to included templates as
  <a class="link" href="language.syntax.attributes.html" title="Attributes">attributes</a>.
  Any variables explicitly passed to an included template
   are only available within the scope of the included
  file. Attribute variables override current template variables, in
  the case when they are named the same.
 </p></li>
<li class="listitem"><p>
  You can use all variables from the including template inside the included template. 
  But changes to variables or new created variables inside the included template
  have local scope and are not visible inside the including template after the 
  <code class="varname">{include}</code> statement. This default behaviour can be changed for 
  all variables assigned in the included template by using the scope attribute at the
  <code class="varname">{include}</code> statement or for individual variables by using the scope
   attribute at the <a class="link" href="language.function.assign.html" title="{assign}"><code class="varname">{assign}</code></a>
   statement. The later is useful to return values from the included template to the 
   includung template.
  </p></li>
<li class="listitem"><p>
  Use the syntax for <a class="link" href="resources.html" title="Chapter 16. Resources">template resources</a> to
  <code class="varname">{include}</code> files outside of the
  <a class="link" href="variable.template.dir.html" title="$template_dir"><em class="parameter"><code>$template_dir</code></em></a>  directory.
  </p></li>
</ul></div>
<p><span class="bold"><strong>Attributes:</strong></span></p>
<div class="informaltable"><table border="1">
<colgroup>
<col align="center">
<col align="center">
<col align="center">
<col align="center">
<col>
</colgroup>
<thead><tr>
<th align="center">Attribute Name</th>
<th align="center">Type</th>
<th align="center">Required</th>
<th align="center">Default</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr>
<td align="center">file</td>
<td align="center">string</td>
<td align="center">Yes</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>The name of the template file to include</td>
</tr>
<tr>
<td align="center">assign</td>
<td align="center">string</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>The name of the variable that the output of
      include will be assigned to</td>
</tr>
<tr>
<td align="center">cache_lifetime</td>
<td align="center">integer</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>Enable caching of this subtemplate with an individual cache lifetime</td>
</tr>
<tr>
<td align="center">compile_id</td>
<td align="center">string/integer</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>Compile this subtemplate with an individual compile_id</td>
</tr>
<tr>
<td align="center">cache_id</td>
<td align="center">string/integer</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>Enable caching of this subtemplate with an individual cache_id</td>
</tr>
<tr>
<td align="center">scope</td>
<td align="center">string</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>Define the scope of all in the subtemplate assigned variables: 'parent','root' or 'global'</td>
</tr>
<tr>
<td align="center">[var ...]</td>
<td align="center">[var type]</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>variable to pass local to template</td>
</tr>
</tbody>
</table></div>
<p><span class="bold"><strong>Option Flags:</strong></span></p>
<div class="informaltable"><table border="1">
<colgroup>
<col align="center">
<col>
</colgroup>
<thead><tr>
<th align="center">Name</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr>
<td align="center">nocache</td>
<td>Disables caching of this subtemplate</td>
</tr>
<tr>
<td align="center">caching</td>
<td>Enable caching of this subtemplate</td>
</tr>
<tr>
<td align="center">inline</td>
<td>If set merge the compile code of the subtemplate into the compiled calling template</td>
</tr>
</tbody>
</table></div>
<div class="example">
<a name="id375045"></a><p class="title"><b>Example 7.46. Simple {include} example</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;html&gt;
&lt;head&gt;
  &lt;title&gt;{$title}&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
{include file='page_header.tpl'}

{* body of template goes here, the $tpl_name variable
   is replaced with a value eg 'contact.tpl'
*}
{include file="$tpl_name.tpl"}

{* using shortform file attribute *}
{include 'page_footer.tpl'}
&lt;/body&gt;
&lt;/html&gt;

  </pre></div>
</div>
<br class="example-break"><div class="example">
<a name="id375058"></a><p class="title"><b>Example 7.47. {include} passing variables</b></p>
<div class="example-contents">
<pre class="programlisting">

{include 'links.tpl' title='Newest links' links=$link_array}
{* body of template goes here *}
{include 'footer.tpl' foo='bar'}

  </pre>
<p>The template above includes the example <code class="filename">links.tpl</code> below</p>
<pre class="programlisting">

&lt;div id="box"&gt;
&lt;h3&gt;{$title}{/h3&gt;
&lt;ul&gt;
{foreach from=$links item=l}
.. do stuff  ...
&lt;/foreach}
&lt;/ul&gt;
&lt;/div&gt;

</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id375096"></a><p class="title"><b>Example 7.48. {include} using parent scope</b></p>
<div class="example-contents">
<p>Variables assigned in the included template will be seen in the including template.</p>
<pre class="programlisting">

{include 'sub_template.tpl' scope=parent}
...
{* display variables assigned in sub_template *}
{$foo}&lt;br&gt;
{$bar}&lt;br&gt;
...

  </pre>
<p>The template above includes the example <code class="filename">sub_template.tpl</code> below</p>
<pre class="programlisting">

...
{assign var=foo value='something'}
{assign var=bar value='value'}
...

</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id375131"></a><p class="title"><b>Example 7.49. {include} with disabled caching</b></p>
<div class="example-contents">
<p>The included template will not be cached.</p>
<pre class="programlisting">

{include 'sub_template.tpl' nocache}
...

  </pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id375148"></a><p class="title"><b>Example 7.50. {include} with individual cache lifetime</b></p>
<div class="example-contents">
<p>In this example included template will be cached with an individual cache lifetime of 500 seconds.</p>
<pre class="programlisting">

{include 'sub_template.tpl' cache_lifteime=500}
...

  </pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id375165"></a><p class="title"><b>Example 7.51. {include} with forced caching</b></p>
<div class="example-contents">
<p>In this example included template will be cached independent of the global cahing setting.</p>
<pre class="programlisting">

{include 'sub_template.tpl' caching}
...

  </pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id375183"></a><p class="title"><b>Example 7.52. {include} and assign to variable</b></p>
<div class="example-contents">
<p>This example assigns the contents of <code class="filename">nav.tpl</code>
    to the <code class="varname">$navbar</code> variable,
   which is then output at both the top and bottom of the page.
   </p>
<pre class="programlisting">
 
&lt;body&gt;
  {include 'nav.tpl' assign=navbar}
  {include 'header.tpl' title='Smarty is cool'}
    {$navbar}
    {* body of template goes here *}
    {$navbar}
  {include 'footer.tpl'}
&lt;/body&gt;

   </pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id375212"></a><p class="title"><b>Example 7.53. {include} with relative paths</b></p>
<div class="example-contents">
<p>This example includes another template relative to the directory of the current template.</p>
<pre class="programlisting">

   {include 'template-in-a-template_dir-directory.tpl'}
   {include './template-in-same-directory.tpl'}
   {include '../template-in-parent-directory.tpl'}

    </pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id375232"></a><p class="title"><b>Example 7.54. Various {include} resource examples</b></p>
<div class="example-contents"><pre class="programlisting">

{* absolute filepath *}
{include file='/usr/local/include/templates/header.tpl'}

{* absolute filepath (same thing) *}
{include file='file:/usr/local/include/templates/header.tpl'}

{* windows absolute filepath (MUST use "file:" prefix) *}
{include file='file:C:/www/pub/templates/header.tpl'}

{* include from template resource named "db" *}
{include file='db:header.tpl'}

{* include a $variable template - eg $module = 'contacts' *}
{include file="$module.tpl"}

{* wont work as its single quotes ie no variable substitution *}
{include file='$module.tpl'}

{* include a multi $variable template - eg amber/links.view.tpl *}
{include file="$style_dir/$module.$view.tpl"}

  </pre></div>
</div>
<br class="example-break"><p>
  See also
  <a class="link" href="language.function.include.php.html" title="{include_php}"><code class="varname">{include_php}</code></a>,
  <a class="link" href="language.function.insert.html" title="{insert}"><code class="varname">{insert}</code></a>,
  <a class="link" href="language.function.php.html" title="{php}"><code class="varname">{php}</code></a>,
  <a class="link" href="resources.html" title="Chapter 16. Resources">template resources</a> and
  <a class="link" href="tips.componentized.templates.html" title="Componentized Templates">componentized templates</a>.
 </p>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="language.function.if.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="language.builtin.functions.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="language.function.include.php.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">{if},{elseif},{else} </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> {include_php}</td>
</tr>
</table>
</div>
</body>
</html>
